OpenEuphoria

define_c_proc

include dll.e 
namespace dll 
public function define_c_proc(object lib, object routine_name, sequence arg_types) 

defines the characteristics of either a C function, or a machine-code routine that you wish to call as a procedure from your Euphoria program.

Parameters:

1. lib : an object, either an entry point returned as an atom by open_dll, or "" to denote a routine the RAM address is known.
2. routine_name : an object, either the name of a procedure in a shared object or the machine address of the procedure.
3. argtypes : a sequence of type constants.

Returns:

A small integer, known as a routine id, will be returned.

Errors:

The length of name should not exceed 1_024 characters.

Comments:

Use the returned routine id as the first argument to c_proc when you wish to call the routine from Euphoria.

A returned value of -1 indicates that the procedure could not be found or linked to.

On Windows you can add a '+' character as a prefix to the procedure name. This tells Euphoria that the function uses the cdecl calling convention. By default, Euphoria assumes that C routines accept the stdcall convention.

When defining a machine code routine, lib must be the empty sequence, "" or {}, and routine_name indicates the address of the machine code routine. You can poke the bytes of machine code into a block of memory reserved using allocate. On Windows the machine code routine is normally expected to follow the stdcall calling convention, but if you wish to use the cdecl convention instead you can code {'+', address} instead of address.

argtypes is made of type constants, which describe the C types of arguments to the procedure. They may be used to define machine code parameters as well.

The C function that you define could be one created by the Euphoria To C Translator, in which case you can pass Euphoria data to it, and receive Euphoria data back. A list of Euphoria types is shown above.

You can pass any C integer type or pointer type. You can also pass a Euphoria atom as a C double or float.

Parameter types which use 4 bytes or less are all passed the same way, so it is not necessary to be exact.

Currently, there is no way to pass a C structure by value. You can only pass a pointer to a structure. However, you can pass a 64 bit integer by pretending to pass two C_LONG instead. When calling the routine, pass low doubleword first, then high doubleword.

The C function can return a value but it will be ignored. If you want to use the value returned by the C function, you must instead define it with define_c_func and call it with c_func.

Example 1:

atom user32 
integer ShowWindow 
 
-- open user32.dll - it contains the ShowWindow C function 
user32 = open_dll("user32.dll") 
 
-- It has 2 parameters that are both C int. 
ShowWindow = define_c_proc(user32, "ShowWindow", {C_INT, C_INT}) 
-- If ShowWindow used the cdecl convention,  
-- we would have coded "+ShowWindow" here 
 
if ShowWindow = -1 then 
    puts(1, "ShowWindow not found!\n") 
end if 

See Also:

c_proc, define_c_func, c_func, open_dll